Summary

Consolidates the eight-PR friendlier-errors stack into a single PR. Inspired by @Schniz's stalled #706. Superseded by this PR: #1831, #1832, #1836, #1837, #1838, #1839, #1840.

What's included

Fixes from manual testing (createHook() inside a step)

Surfaced three issues after running the earlier stack end-to-end and addressed in the final commits:

1. ANSI bytes were leaking into .message because chalk resolves at construction time — fixed by storing plain text and rendering pretty lazily (see context-errors-plain-message changeset).
2. Context violations were retrying 3× and producing 4 duplicated log blocks — fixed by marking them fatal: true and widening FatalError.is() (see context-errors-fatal changeset).
3. Duplicated captureStackTrace feature-detect in two files — fixed by extracting a shared redirectStackToCaller helper (see capture-stack-shared changeset).

Follow-up round (latest commits)

Manual testing uncovered two more issues, fixed in the last two commits on this branch:

4. SerializationError still looped through 4 retries. Root cause: dehydrateStepReturnValue() was called outside the step-handler try/catch, so FatalError.is() never saw the error. Two-part fix: mark SerializationError as fatal = true, and move the dehydration call inside the user-code try/catch in step-handler.ts so the error routes through userCodeFailed → step_failed (see serialization-error-fatal changeset). Same non-POJO return now fails in ~1.6s / 1 block, not ~21s / 4 blocks.
5. Snapshot tests for log output. Added toMatchInlineSnapshot-backed tests for describeError() payloads (every attribution path) and the scoped-logger call signature for the two canonical runtime failure sites. Regression gate on the exact field shapes users see in their log drains.

Post-review polish (latest commits)

Driven by manual testing in tmux + reviewer feedback after the initial review pass:

6. Logger layout overhaul. Composed framing + structured fields (user error · FatalError, run wrun_…, step step_… · add (./workflows/x)) between the framing line and the stack body, instead of after — the most useful info now sits at the top of each block instead of being buried under 30+ stack lines.
7. Stack trim. composeLogLine() drops framework-internal frames (node_modules/.pnpm/, node:internal/, Turbopack-bundled node_modules__pnpm_* and _next_dist_* chunks) and caps the surviving frames at 6. Suppressed runs emit one summary line so users know the stack was trimmed.
8. Friendly step / workflow names in framings. step//./workflows/foo//bar renders as bar (./workflows/foo) everywhere we log a step or workflow name, via new formatStepName / formatWorkflowName helpers in @workflow/utils.
9. Consistent ╰▶ hint: / ╰▶ docs: framing across all errors with hints or docs slugs. WorkflowError, SerializationError, and WorkflowBuildError now share one appendFramedDetails helper, matching the box-drawing tree ContextViolationError already used. The blank-line-separated Learn more: <url> style is gone.
10. Single hint, lives on the error message. Dropped the duplicate hint field from runtime logger metadata. Hints get serialized into the event log on the message itself, rehydrate on the workflow side, and surface in observability. The previous logger-only hint duplicated stderr but never made it past the step boundary.
11. Better serialization-failure hint. Updated to point at the foundations doc instead of a hardcoded (plain objects, arrays, primitives, …) list, which drifted out of sync as the supported types grew. Reuses across step args, workflow args/return, stream messages, and any other site that goes through formatSerializationError.
12. Workbench route no longer double-logs failures. app/api/workflows/start/route.ts's SSE wrapper was catching WorkflowRunFailedError rejection and re-emitting it via console.error('Error in workflow stream:', error) + controller.error(error), which then triggered Next.js's ⨯ failed to pipe response overlay. The SDK already logs the failure cleanly, so the wrapper now closes the stream gracefully on WorkflowRunFailedError.
13. ErrorStackBlock title trim in web observability. Multi-line error messages (Failed to serialize step return value\n╰▶ hint: …) were rendering the entire framed body in the card title, pushing the copy button off-screen. Title now shows just the first non-empty trimmed line with single-line truncation; full message stays in the body via Error.stack.
14. Persisted error message no longer embeds the machine step name. Step "step//./.../foo" failed after N retries: … and Step "step//.../foo" exceeded max retries (…) now read Step failed after N retries: … / Step exceeded max retries (…). Observability already attributes the event to a specific step via the UI tree.
15. Retry summary reads 4 attempts · 3 max retries instead of 3 retries (which was ambiguous next to "4 attempts").
16. WorkflowError no longer leaks cause: undefined as an enumerable own property when no cause is provided — every subclass's util.inspect(err) output stays clean.
17. ContextViolationError [util.inspect.custom] counted message lines correctly when slicing the stack tail, fixing duplicated ╰▶ docs: lines on multi-detail errors.
18. Step-handler integration tests for fatal vs non-fatal retry-loop wiring: a fatal: true error emits one step_failed and zero step_retrying; a non-fatal Error retries via step_retrying until the budget is exhausted, then emits step_failed. Catches the silent-regression case where fatal = true is removed from a class but FatalError.is() unit tests stay green.

Addressed review feedback

• VaguelySerious (Friendlier context-violation errors + Ansi renderer #1831): "I don't like errors package depending on chalk" — Ansi is now on a subpath; the main entry has no chalk dep path.
• Copilot (Friendlier workflow errors (consolidated) #1849): "Duplicated Error.captureStackTrace guard/cast" — extracted to packages/core/src/capture-stack.ts.
• Copilot (Friendlier context-violation errors + Ansi renderer #1831): Ansi subpath export concern — same subpath fix covers this.
• VaguelySerious (Friendlier workflow errors (consolidated) #1849, blocking): "[util.inspect.custom] duplicates every detail line" — fixed by counting message lines instead of slicing only the first.
• VaguelySerious (Friendlier workflow errors (consolidated) #1849): "cause: undefined enumerable own property" — wrapped the assignment in if (options?.cause !== undefined).
• VaguelySerious (Friendlier workflow errors (consolidated) #1849): "Add an integration test on the retry loop" — added a fatal-vs-retryable describe block that asserts step_failed/step_retrying event counts directly.
• VaguelySerious (Friendlier workflow errors (consolidated) #1849): "Drastically shorten the changesets" — consolidated 15 file-by-file entries into a single friendlier-errors.md covering core/errors/builders/utils.

Manual test plan

All sections below exercise different parts of the stack. Start cd workbench/nextjs-turbopack && pnpm dev unless otherwise noted.

1. Context-violation errors (phase 1 + 2 + followups)

A convenient smoke route at workbench/nextjs-turbopack/app/api/friendlier-errors-smoke/route.ts:

import { NextResponse } from 'next/server';
import { createHook, sleep, getStepMetadata, getWorkflowMetadata } from 'workflow';

export async function GET(req: Request) {
  const which = new URL(req.url).searchParams.get('which');
  try {
    if (which === 'createHook') createHook();
    if (which === 'sleep') await sleep('1s');
    if (which === 'getStepMetadata') getStepMetadata();
    if (which === 'getWorkflowMetadata') getWorkflowMetadata();
    return NextResponse.json({ ok: true });
  } catch (err) {
    console.error(err);
    return NextResponse.json(
      { name: (err as Error).name, message: (err as Error).message, stack: (err as Error).stack },
      { status: 500 }
    );
  }
}

• createHook() outside workflow — ?which=createHook. Terminal shows a framed box with title `createHook()` can only be called inside a workflow function and a docs: https://…/workflow/create-hook line (polished — no longer note: Read more about…).
• sleep() outside workflow — ?which=sleep. Same framing, docs URL ends in .../workflow/sleep.
• getStepMetadata() in a workflow function (not a step) — add to a "use workflow" file; expect title "can only be called inside a step function".
• getWorkflowMetadata() in application code — ?which=getWorkflowMetadata. Expect "workflow or step function".
• resumeHook() inside a workflow — call resumeHook(token, payload) from inside a "use workflow" function. Title: `resumeHook()` cannot be called from a workflow context, plus a line this call was made from the workflow//./src/workflows/example.ts//myWorkflow workflow context. with the workflow/ prefix dimmed.
• Stack points at user code — in the JSON response body, the first at ... line of err.stack should reference your route handler, not a frame inside @workflow/core. Same goes for the Next.js dev overlay.
• No functionName leak — the JSON response body should NOT contain a functionName property on the error object (it used to via the old constructor param-property).
• ANSI bytes don't leak into .message / .stack (new in this PR) — the JSON response body's message and stack strings must contain no \x1B[ bytes; they're plain text. In the terminal, console.error(err) still renders the pretty framed version via util.inspect.
• Context violations fail fast (no 4× retries) (new in this PR) — call createHook() inside a "use step" function:

  async function add(a: number, b: number): Promise<number> {
    'use step';
    createHook();
    return a + b;
  }

  Run a workflow that calls add(…). You should see one [workflow-sdk] fatal-error log block (Step "X" threw a FatalError — bubbling up...), not four. The step fails immediately.

2. Runtime logger metadata (phase 3)

• Standardized prefix — all runtime log lines start with [workflow-sdk]. Grep your terminal output; there should be no [Workflows] or other prefixes.
• Run context attached without repetition — trigger any workflow; log lines carry workflowRunId and workflowName as metadata fields instead of being baked into the message string.
• Replay-timeout phrasing:
  • While retries remain: warn level, phrasing includes "took too long — will retry".
  • After final attempt: error level, phrasing includes "gave up".
• Error stack surfaces in log drain — set up a log drain (or pipe to a file) and confirm the stack is included as a structured field (errorStack), not just the one-line error message.

3. SerializationError (phase 4)

Cause a user-facing serialization failure:

async function stepThatLeaks(): Promise<Map<string, { fn: () => void }>> {
  'use step';
  return new Map([['foo', { fn: () => console.log('unserializable') }]]);
}

• Run the workflow. Expect [workflow-sdk] log with errorName: 'SerializationError'.
• errorAttribution: 'user'.
• Hint is rendered as a ╰▶ hint: line on the error message itself — the URL points at https://workflow-sdk.dev/docs/foundations/serialization (foundations doc, not a hardcoded type list). The hint travels with the persisted event into observability.
• Stream locking: call getWritable('x').getWriter() twice on the same stream — expect a SerializationError with the same ╰▶ hint: framing.

4. describeError attribution (phase 5)

For each of these, inspect the [workflow-sdk] log at failure time:

• Plain user Error — throw new Error('boom') from a step → errorAttribution: 'user', no framed hint on the message.
• SerializationError → errorAttribution: 'user' + ╰▶ hint: line on the message pointing at the foundations doc.
• Context-violation error → errorAttribution: 'user' + ╰▶ docs: line on the message pointing at the per-API reference page.
• WorkflowRuntimeError — throw new WorkflowRuntimeError('invariant') from a step → errorAttribution: 'sdk'.
• Replay timeout — set WORKFLOW_REPLAY_TIMEOUT_MS=50, run a non-trivial workflow → after retries exhaust, errorAttribution: 'sdk', errorCode: 'REPLAY_TIMEOUT'.
• Max-delivery exhaustion — write a step that always throws; after queue max-delivery budget exhausts → errorAttribution: 'sdk', errorCode: 'MAX_DELIVERIES_EXCEEDED'.

Note: describeError(err) and describeRunError({errorCode, errorName}) still return a hint field for CLI / web consumers, but the runtime logger no longer adds it as a duplicate metadata field. Hints live on the error message instead, so they survive serialization and surface in observability.

5. Consistency pass (phase 6)

• Zod schema failure on defineHook().resume() — call hook.resume(token, invalidBody). Expect a readable bulleted list of validation issues (one per line, at "field": message), not a raw JSON dump of ZodError.issues.
• crypto.subtle.generateKey() inside workflow VM — call it from a "use workflow" function. Expect a clear message explaining why it's disabled + "move this into a step function", with errorAttribution: 'sdk'.

6. describeError subpath (phase 7 foundation)

Create scratch.ts at repo root:

import { describeRunError, describeError } from '@workflow/core/describe-error';
import { SerializationError, WorkflowRuntimeError } from '@workflow/errors';

console.log(describeRunError({ errorCode: 'USER_ERROR', errorName: 'SerializationError' }));
console.log(describeRunError({ errorCode: 'USER_ERROR', errorName: 'NotInWorkflowContextError' }));
console.log(describeRunError({ errorCode: 'RUNTIME_ERROR' }));
console.log(describeRunError({ errorCode: 'REPLAY_TIMEOUT' }));
console.log(describeRunError({ errorCode: 'MAX_DELIVERIES_EXCEEDED' }));
console.log(describeRunError({ errorCode: 'USER_ERROR' }));

console.log(describeError(new SerializationError('boom')));
console.log(describeError(new WorkflowRuntimeError('invariant')));
console.log(describeError(new Error('plain')));

Run pnpm tsx scratch.ts.

• describeRunError({ errorCode: 'USER_ERROR', errorName: 'SerializationError' }) → { attribution: 'user', errorCode: 'USER_ERROR', hint: 'A value…serialized…' }.
• describeRunError({ errorCode: 'RUNTIME_ERROR' }) → { attribution: 'sdk', hint: 'This is an internal workflow SDK error…' }.
• Live-error parity — describeError(new SerializationError('x')) and describeRunError({ errorCode: 'USER_ERROR', errorName: 'SerializationError' }) return the same shape and hint string.
• Subpath import works — TypeScript resolves @workflow/core/describe-error and pnpm tsx runs without module-resolution errors.

7. WorkflowBuildError (phase 8)

Exercise the build pipeline, not the runtime. Use workbench/nextjs-turbopack and run pnpm build (not pnpm dev).

• Syntax error in a workflow file → in the build output, expect a WorkflowBuildError titled "Build failed during workflows bundle" followed by a blank line and hint: Review the esbuild errors above…. The original esbuild errors remain printed above (not suppressed).
• Unresolved built-in steps — mv node_modules/workflow node_modules/workflow-bak and run pnpm build. Expect WorkflowBuildError: Failed to resolve built-in steps sources. + hint: run \pnpm install workflow`…`. Restore afterwards.
• Empty workflow directory — move all workflow files aside. Expect WorkflowBuildError: No output files generated from esbuild + hint mentioning "use workflow" / "use step" directives.
• .is() discriminator — in a scratch script: WorkflowBuildError.is(new WorkflowBuildError('x', { hint: 'y' })) returns true; WorkflowBuildError.is(new Error('x')) returns false.
• Runtime paths unaffected — run a normal workflow at runtime (pnpm dev). Confirm no WorkflowBuildError shows up; this class is build-time only.

8. New @workflow/errors/ansi subpath (final PR)

• import { Ansi } from '@workflow/errors' no longer works (and wasn't intended to — the helpers were always namespaced). Confirm import * as Ansi from '@workflow/errors/ansi' resolves.
• A package that imports only error classes (import { SerializationError } from '@workflow/errors') no longer pulls chalk into its bundle. Check a production bundle or pnpm why chalk from a dependent context.

9. FatalError.is() widening (final PR)

• FatalError.is(new FatalError('x')) — true.
• FatalError.is(new NotInWorkflowContextError('createHook()', 'https://…')) — true (via fatal: true own property).
• FatalError.is(new Error('x')) — false.
• FatalError.is({ fatal: true }) — false (must be an Error-shaped value).

Unit tests

All packages typecheck clean; relevant test files pass:

• pnpm --filter @workflow/errors test — 26 tests (Ansi, SerializationError, WorkflowBuildError, FatalError widening, framed-details consolidation)
• pnpm --filter @workflow/core exec vitest run src/log-format.test.ts src/logger.test.ts src/context-errors.test.ts src/describe-error.test.ts src/runtime/step-handler.test.ts — 76 tests, including new composeLogLine snapshot tests and the fatal-vs-retryable step-handler integration suite
• pnpm --filter @workflow/builders test — 129 tests
• pnpm typecheck — clean across workspace

Smoke-test harness (local)

For reviewers reproducing the manual test plan, a one-shot tmux harness lives at /tmp/wf-1849-smoke.sh (built during testing). Pane layout:

┌─ dev server :3010 ──────────┬─ workflow web :3011 ──┐
│  pnpm dev (next.js + sdk)   │  pnpm workflow web    │
├──────────────────────────────┴───────────────────────┤
│  /tmp/wf-1849-smoke.sh ok | fatal | retryable |     │
│                       serialization | context-step  │
│                       ctx-create | ctx-sleep | ...  │
│                       all                            │
└──────────────────────────────────────────────────────┘

The harness's workbench/nextjs-turbopack/workflows/smoke.ts and app/api/friendlier-errors-smoke/route.ts are kept out of git (workbench-local) — set them up via the workflow-init-style instructions in the prior conversation if you want to reuse the harness.

🤖 Generated with Claude Code